cli: clarify event overview/timeline/list --ai-help to prevent unreachable polling predicates#297
Merged
Merged
Conversation
…hable polling predicates A real AI session burned its full 5-minute foreground-Bash timeout polling "event overview" with `grep -q event_type` — a predicate unreachable by construction because overview returns only millisecond-epoch timestamp buckets, no event content. The previous --ai-help said overview gave a "high-level summary of event activity" without showing the output shape, which an AI can reasonably read as "richer than just timestamps". This commit extends the three relevant explain blocks so any AI reading --ai-help cold can pick the right tool the first time: - event overview: shows the actual output shape (flat list of ms epochs), what empty looks like (`[]`), what overview is good for, and an explicit "do not use this for sampling content or for predicates keyed on in-payload fields — those are unreachable, you will spin until timeout." - event timeline: alias, points at event overview's expanded text. - event list: notes the empty result is the literal `[]` and that structural empty-vs-non-empty against `[]` is the reliable presence predicate — not greping for in-payload strings. No behavior change; --ai-help text only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
event overview --ai-helpnow shows the actual output shape (flat list of ms-epoch timestamps; empty is[]) and an explicit "do not use this for sampling event content or for predicates keyed on in-payload fields — those are unreachable, you will spin until timeout."event timeline --ai-help(alias) points at the expanded overview text.event list --ai-helpnotes the empty result is the literal[]and that the structural empty-check is the reliable presence predicate — not greping for in-payload substrings.Why
A real AI onboarding session burned its full 5-minute foreground-Bash timeout polling
limacharlie event overview ... | grep -q event_type. That predicate is unreachable by construction —event overviewreturns only millisecond-epoch timestamp buckets, no event content. The previous--ai-helpsaid overview gave a "high-level summary of event activity" without showing the output shape, which an AI can reasonably read as "richer than just timestamps" and pick wrong.This change makes the right choice obvious to any AI reading
--ai-helpcold:event list --limit N[], not in-payload substringsNotes
--ai-helptext only.--ai-helprenders end-to-end viapython -m limacharlie event overview --ai-help.Test plan
limacharlie event overview --ai-helpshows the new output-shape section + "do not use" calloutslimacharlie event timeline --ai-help(alias) points at overview's expanded helplimacharlie event list --ai-helpmentions empty =[]and the structural empty-check rule